home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / tpref.exe / TPR10.TXT < prev    next >
Text File  |  1992-10-19  |  66KB  |  1,642 lines
  1.                                   Chapter 10
  2.                                     of the
  3.                             Turbo Pascal Reference
  4.  
  5.                           The Turbo Vision Reference
  6.                                   (continued)
  7.  
  8. This chapter is part of the Turbo Pascal Reference electronic freeware book (C)
  9. Copyright 1992 by Ed Mitchell.  This freeware book contains supplementary
  10. material to Borland Pascal Developer's Guide, published by Que Corporation,
  11. 1992.  However, Que Corporation has no affiliation with nor responsibility for
  12. the content of this free book.  Please see Chapter 1 of the Turbo Pascal
  13. Reference for important information about your right to distribute and use this
  14. material freely.  If you find this material of use, I would appreciate your
  15. purchase of one my books, such as the Borland Pascal Developer's Guide or
  16. Secrets of the Borland C++ Masters, Sams Books, 1992.  Thank you.
  17.  
  18. For additional information on using Turbo Vision, including a detailed
  19. tutorial, please see Chapters 11 through 16 of the Borland Pascal Developer's
  20. Guide.
  21.  
  22.  
  23. TScrollBar object
  24. ------------------------------------------------------------ 
  25. Turbo Vision Hierarchy
  26.   TObject
  27.      TView
  28.        TScrollBar
  29.  
  30. Discussion
  31.      Use TScrollBar to create scroll bar objects for list boxes, list viewers
  32.      and anywhere else, such as text editors, where the user can scroll through
  33.      text or lists.  When scroll bars are linked to a TListBox or TListViewer,
  34.      these objects automatically update the TScrollBar fields.  As a result,
  35.      when using TScrollBar in conjunction with the list viewers, all you need
  36.      to do is Init a new scrollbar are the respective fields of TScrollBar are
  37.      automatically set so that the scroll bar moves in tandem with movements in
  38.      the list box.  Conversely, whenever the scroll bar is adjusted with the
  39.      mouse, the scrollbar uses the Message function to broadcast the changes to
  40.      the owner of the scroll bar.
  41.  
  42. Example
  43.     { Define the location of the scroll bar relative to the List viewer }
  44.   BarBounds := Bounds;
  45.   BarBounds.B.X := BarBounds.B.X + 1;
  46.   BarBounds.A.X := Bounds.B.X;
  47.   { Create a new scroll bar at the specified location }
  48.   ListScroller := New (PScrollBar, Init(BarBounds));
  49.   { Now create the list viewer (PDirList is derived from
  50.      TListViewer) and link the list viewer to its scroll bar }
  51.   ListObject := New(PDirList, 
  52.           Init(Bounds, 1, NIL, ListScroller ));
  53.   { Insert both objects into the owning group window }
  54.   Insert(ListScroller);
  55.   Insert(ListObject);
  56.  
  57. Commonly Used Features
  58.      If you are using TScrollBar in conjunction with TListViewer or TListBox,
  59.      you will mostly use only the Init method.  However, if you are using
  60.      scroll bars for other purposes, you will likely access the SetParams,
  61.      SetRange, SetStep and SetValue methods.
  62.  
  63. Fields
  64. ArStep: Integer; { Read only }
  65.      This field holds the amount to change Value by when the up or down arrow
  66.      keys are pressed, or if a mouse click is made in the up or down arrow
  67.      icons.  The default value is 1.
  68.      See:  TScrollBar.SetParams
  69.  
  70. Max: Integer; { Read only }
  71.      Max contains the upper limit for the scroll bar range of values.
  72.      See:  Min, Value, TScrollBar.SetParams, TScrollBar.SetRange
  73.  
  74. Min: Integer; { Read only }
  75.      Holds the minimum value for the scroll bar range.
  76.      See:  Max, TScrollBar.SetParams, TScrollBar.SetRange
  77.  
  78. PgStep: Integer; { Read only }
  79.      When the page up or down keys are pressed, or a mouse click is made in the
  80.      paging area either side of the scroll bar marker, PgStep is the amount by
  81.      which Value should be adjusted (PgStep is added or substracted to Value
  82.      depending upon the direction).
  83.  
  84. Value: Integer; { Read only }
  85.      Value keeps track of the current location of the scroll bar marker (what
  86.      the Macintosh people call a "thumb") that you can drag along the scroll
  87.      bar with the mouse to perform quick scrolling manuevers.  Values ranges
  88.      from Min up to the maximum value, Max, set by calling TScrollBar.SetRange.
  89.      See:  Max, Min, TScrollBar.SetParams, TScrollBar.SetRange,
  90.      TScrollBar.SetValue
  91.  
  92. Methods
  93. procedure Draw; virtual;
  94.      Draws the scroll bar.
  95.  
  96. function GetPalette: PPalette; virtual;
  97.      Returns a pointer to the CScrollBar palette, but this function may be
  98.      overriden to return a pointer to a new palette.
  99.  
  100. procedure HandleEvent(var Event: TEvent); virtual;
  101.      Like most views, this is the central location for processing of the mouse
  102.      and keyboard events that cause the scroll bar to change its position.
  103.  
  104. constructor Init(var Bounds: TRect);
  105.      Use Init to create the scroll bar object and to specify the Bounds where
  106.      the scroll bar should be position.  If the X width specifed by Bounds.A
  107.      and Bounds.B equals 1, then a vertical scroll bar is created.  For all
  108.      other X widths, a horizontal scroll bar is created.
  109.  
  110. constructor Load(var S: TStream);
  111.      Creates and reads a scroll bar object from stream S.
  112.  
  113. procedure ScrollDraw; virtual;
  114.      Every time Value changes, ScrollDraw is called to send evBroadcast message
  115.      to the owner of this scroll bar.
  116.      See:  cmXXXX constants, Message
  117.  
  118. function ScrollStep(Part: Integer): Integer; virtual;
  119.      Part is one of the sbXXXX constants, such as sbUpArrow or sbPageDown. 
  120.      ScrollStep determines by how much the Value field should change if one of
  121.      these items was selected by a mouse click, and returns the result.
  122.      See:  sbXXXX constants
  123.  
  124. procedure SetParams(AValue, AMin, AMax, APgStep, AArStep : Integer );
  125.      Use SetParams to initialize all of the various TScrollBar fields.  See the
  126.      field definitions provided above for more information.
  127.  
  128. procedure SetRange(AMin, AMax: Integer);
  129.      Call SetRange to set the Min and Max fields to the parameter values. 
  130.      Thesespecify the range over which the scroll bar will operate.  For
  131.      example, in a list of 100 items, you would write,
  132.             SetRange(0, 100);
  133.  
  134. procedure SetStep(APgStep, AArStep: Integer);
  135.      PgStep and ArStep define how far to move the scroll bar marker for paging
  136.      and single movements, respectively.  Call SetStep to set the PgStep and
  137.      ArStep fields to the parameter values.
  138.      See:  TScrollBar.SetParams, ArStep, PgStep fields
  139.  
  140. procedure SetValue(AValue: Integer);
  141.      Use SetValue to change the position of the scroll bar marker.  This will
  142.      cause the scroll bar to be redrawn with the marker at the new positions.
  143.  
  144. procedure Store(var S: TStream);
  145.      Writes the TScrollBar object to stream S.
  146.  
  147.  
  148.  
  149. TScrollChars type
  150. ------------------------------------------------------------ 
  151. Declaration:  
  152.      TScrollChars = array[0..4] of Char;
  153.  
  154. Unit:     Views
  155.  
  156. Purpose:
  157.      This is an internal type used inside TScrollBar to store the characters
  158.      used to draw a TSCrollBar object on the display.
  159.  
  160.  
  161.  
  162. TScroller object
  163. ------------------------------------------------------------ 
  164. Turbo Vision Hierarchy
  165.   TObject
  166.      TView
  167.        TScroller
  168.           TTextDevice
  169.             TTerminal
  170.  
  171. Discussion
  172.      TScroller is primarily of use in providing functionality, ultimately for
  173.      the descendant TTerminal type.  
  174.  
  175. Example
  176.      See TTerminal.
  177.  
  178. Fields
  179. Delta : TPoint; { Read only }
  180.      The X and Y values of the TPoint record contain the relative positions of
  181.      the scrolled positions.  
  182.  
  183. HScrollBar: PScrollBar; { Read only }
  184.      Points to the horizontal scroll bar linked to this scroller, or is nil if
  185.      there is no horizontal scroll bar.
  186.  
  187. Limit: TPoint; { Read only }
  188.      The X and Y fields of the TPoint record contain the maximum values for
  189.      Delta's X and Y fields.
  190.  
  191. VScrollBar: PScrollBar; { Read only }
  192.      Points to the vertical scroll bar linked to this scroller, or is nil if
  193.      there is no vertical scroll bar.
  194.  
  195. Methods
  196. procedure ChangeBounds(var Bounds: TRect); virtual;
  197.      Use ChangeBounds to change the size of the scroller.
  198.  
  199. function GetPalette: PPalette; virtual;
  200.      Returns a pointer to the default scroller color palette, CScroller, and
  201.      may be overridden to provide other color mappings.
  202.  
  203. procedure HandleEvent(var Event: TEvent); virtual;
  204.      Handles TScroller events, most of which are passed to TView.HandleEvent.
  205.  
  206. constructor Init(var Bounds: TRect; AHScrollBar, AVScrollBar: PScrollBar);
  207.      Performs initialization of the TScroller object, giving it the size and
  208.      position specified by Bounds, and linking it to the horizontal and
  209.      vertical scrollbars passed to it as parameters.  If there is no horizontal
  210.      or vertical scrollbar, the respective parameters may be set to nil.
  211.  
  212. constructor Load(var S: TStream);
  213.      Creates and reads a TScroller object from stream S.
  214.  
  215. procedure ScrollDraw; virtual;
  216.      Tests the value of Delta to the current scrollbar positions.  If the
  217.      scrollbars have changed (or conversely, Delta has changed), then Delta is
  218.      updated and the scroller is redrawn.
  219.  
  220. procedure ScrollTo(X, Y: Integer);
  221.      Sets the horizontal scroll bar to the positions specified by X, and the
  222.      vertical scrollbar to the position specified by Y.
  223.  
  224. procedure SetLimit(X, Y: Integer);
  225.      Set's the Limit field to the values passed in X and Y, and updates the
  226.      scrollbars.
  227.  
  228. procedure SetState(AState: Word; Enable: Boolean); virtual;
  229.      Passes its parameters to TView.SetState (see TView.SetState), and then if
  230.      necessary, displays the scroll bars.
  231.  
  232. procedure Store(var S: TStream);
  233.      Writes this TScroller object to stream S.
  234.  
  235.  
  236. TSItem type
  237. ------------------------------------------------------------ 
  238. Declaration:  
  239.      TSItem = record
  240.        Value : PString;
  241.        Next : PSItem;
  242.      end;
  243.  
  244. Purpose:
  245.      TSItem is used in conjunction with NewSItem for creating a linked list of
  246.      strings.   See NewSItem for an example using this data type.
  247.  
  248.  
  249. TSortedCollection object
  250. ------------------------------------------------------------ 
  251. Turbo Vision Hierarchy
  252.   TObject
  253.      TCollection
  254.        TSortedCollection
  255.           TStringCollection
  256.  
  257. Discussion
  258.      When you want to have your collection sorted into some order (that you
  259.      specify), use the TSortedCollection type.   Items added to a
  260.      TSortedCollection are always ordered by the order you specify with a
  261.      custom, overridden TSortedCollection.Compare function.  Chapter 14,
  262.      "Collections" contains a tutorial on the use of collections and sorted
  263.      collections and includes examples of the use of TSortedCollection.  
  264.      Because the important features are described in Chapter 14, some of the
  265.      descriptions below are kept fairly brief.
  266.  
  267. Commonly Used Features
  268.      In addition to the inherited TCollection.Init, you'll use Insert to add
  269.      new items to the collection, Done to dispose of the collection, and
  270.      finally, you must override KeyOf and Compare.
  271.  
  272. Example
  273.      See Chapter 14, "Collections", in the Borland Pascal Developer's Guide,
  274.      for numerous examples.
  275.  
  276. Fields
  277. Duplicates: Boolean; { Read/Write }
  278.      The default setting of Duplicates is False and this prohibits the addition
  279.      of duplicate entries to the collection.  If you change Duplicates to True,
  280.      new duplicate entries will be inserted just before any other items having
  281.      the same key.
  282.  
  283. Methods
  284. function Compare(Key1, Key2: Pointer): Integer; virtual;
  285. Override:  You must override Compare for your data object type.
  286.      Write a new Compare function to compare Key1^ to Key2^ and return a value
  287.      according to this:
  288.        if  Key1^ < Key2^ then return -1
  289.      if  Key1^ = Key2^ then return 0
  290.      if  Key1^ > Key2^ then return 1
  291.      See Chapter 14, "Collections".
  292.  
  293. function IndexOf(Item: Pointer): Integer; virtual;
  294.      Where Item is a pointer to an object type that is stored in the
  295.      collection, IndexOf returns the Index position where it is located, or -1
  296.      if the Item is not found.
  297.  
  298. procedure Insert(Item: Pointer); virtual;
  299.      Adds the Item to the collection.  If Item already exists in the
  300.      collection, Insert checks the value of the Duplicates field.  If 
  301.      Duplicates is False then the Item is not added, but if Duplicates is True,
  302.      then the Item is inserted just prior to any duplicate entries.
  303.  
  304. function KeyOf(Item: Pointer): Pointer; virtual;
  305. Override:  You must override this function.
  306.      KeyOf returns a pointer to the specific field within the object that is to
  307.      be used as the sort key.  For example,
  308.      function TPersonCollection.KeyOf( Item: Pointer): Pointer;
  309.      begin
  310.        KeyOf := @PPersonInfo(Item)^.Name;
  311.      end;
  312.      Here, the Item pointer is recast to the data object data type so that you
  313.      can access its fields.  The address of the field to be used as the sort
  314.      key is returned as the result.
  315.  
  316. function Search(Key: Pointer; var Index: Integer): Boolean; virtual;
  317.      Use Search to look for specific items in the collection.  Search returns
  318.      True if the item was found, or False otherwise.  If found, Index is set to
  319.      the location in the collection where the item resides.  See the example in
  320.      Chapter 14, "Collections" for how to set up the parameter values to use
  321.      the Search function.
  322.  
  323.  
  324.  
  325. TStaticText object
  326. ------------------------------------------------------------ 
  327. Turbo Vision Hierarchy
  328.   TObject
  329.      TView
  330.        TStaticText
  331.  
  332. Discussion
  333.      Use TStaticText to display string messages within dialog boxes or windows.
  334.      See:  TParamText and TLabel.
  335.  
  336. Commonly Used Features
  337.      Init is used to create and initialize the static text area.  None of the
  338.      other methods are likely to be used.
  339.  
  340. Example
  341.      { The following code centers the status string in the
  342.        message box.  The Max(1, <expression>) is to insure that
  343.        in case the expression  becomes negative, we still pass
  344.        at least a 1 as the X coordinate }
  345.      Bounds.Assign ( Max(1,30 - ((Length(Source) + Length(Dest))
  346.        div 2) ), 2, 58, 5);
  347.      Dialog^.Insert( New(PStaticText, Init( Bounds, Source+
  348.        ' to '+Dest)));
  349.      Desktop^.Insert( Dialog );
  350.  
  351. Fields
  352. Text:  PString;
  353.      Holds a pointer to the string that is displayed as the static text item.
  354.  
  355. Methods
  356. constructor Init(var Bounds: TRect; AText: String );
  357.      Creates the TStaticText object at the location specified by Bounds, and
  358.      copies the AText parameter to the Text^ string.  If the Bounds defines a
  359.      multi-line area, AText will be word wrapped within the rectangle.  If
  360.      AText begins with a Ctrl-C character (Chr(03)) the text will be centered
  361.      within the Bounds area.  You can break the text into multiple lines by
  362.      inserting Ctrl-M (Chr(13)) characters at the beginning of each line break.
  363.  
  364. constructor Load(var S: TStream);
  365.      Creates and reads a TStaticText object from stream S.
  366.  
  367. destructor Done; virtual;
  368.      Disposes of the object.  Is normally called automatically by the owning
  369.      group, such as a dialog or window.
  370.  
  371. procedure Draw; virtual;
  372.      Displays Text^.
  373. function GetPalette: PPalette; virtual;
  374.      Returns a pointer to CStaticText.  Override this function if you wish to
  375.      map to a different location in the color palettes.
  376.  
  377. procedure GetText(var S: String); virtual;
  378.      Returns the string contained in S.  Equivalent to S:= Text^.
  379.  
  380. procedure Store(var S: TStream);
  381.      Writes this object to stream S.
  382.  
  383.  
  384.  
  385. TStatusDef type
  386. ------------------------------------------------------------ 
  387. Declaration:  
  388.  
  389.      TStatusDef = record
  390.        Next: PStatusDef;
  391.        Min, Max : Word;
  392.        Items: PStatusItem;
  393.      end;
  394.  
  395. Unit:     Menus
  396.  
  397. Purpose:
  398.      TStatusDef records are used internally for storing the status line
  399.      definition that is created with the NewStatusDef function.  The various
  400.      components of the record contain:
  401.        Next pointers to the next TStatusDef record in a linked list of status
  402.        line items.  For the last item in the list, Next is set to nil.
  403.        Min and Max are the minimum and maximum values of the help context
  404.        constants for the items on the status line.
  405.        Items points to a TStatusItem record, creating a list of the items
  406.        displayed on the status line, or nil, if there are no items on the
  407.        status line.
  408.  
  409.  
  410. TStatusItem type
  411. ------------------------------------------------------------ 
  412. Declaration:  
  413.  
  414.      TStatusItem = record
  415.        Next: PStatusItem;
  416.        Text: PString;
  417.        KeyCode: Word;
  418.        Command: Word;
  419.      end;
  420.  
  421. Unit:     Menus
  422.  
  423. Purpose:
  424.      TStatusItem is an internal record structure used to hold each status line
  425.      item, and is created by calling the NewStatusKey function.
  426.        Next points to the next TStatusItem record, forming a linked list.
  427.        Text points to the string label of the item, or is nil for invisible
  428.        items.
  429.        KeyCode stores the hot key scan code specified to activate the
  430.        particular command.
  431.        Command contains the cmXXXX constant that is sent in an event record
  432.        when the hot key is pressed or the status line item is selected with a
  433.        mouse.  
  434.  
  435. See: TStatusLine, NewStatusKey
  436.  
  437.  
  438. TStatusLine object
  439. ------------------------------------------------------------ 
  440. Turbo Vision Hierarchy
  441.   TObject
  442.      TView
  443.        TStatusLine
  444.  
  445. Discussion
  446.      The TStatusLine is the object used to represent the status line displayed
  447.      at the bottom of Turbo Vision applications.  You create the status line
  448.      with a call to it's Init constructor, and store a pointer to the status
  449.      line into the global variable StatusLine.  You can also use the
  450.      TStatusLine object to define context senstivie hints that are displayed on
  451.      the status line during the program's execution.
  452.  
  453. Example
  454.      See Chapter 11, "Turbo Vision Tutorial" for examples of status line
  455.      creation and see the example given for the TStatusLine.Update procedure
  456.      below, showing how to add "hint" context sensitive prompts to the status
  457.      line.
  458.  
  459. Fields
  460. Defs: PStatusDef;
  461.      Points to the linked list of TStatusDef records.
  462.  
  463. Items: PStatusItem;
  464.      Points to the linked list of TStatusItems.
  465.  
  466. Methods
  467. destructor Done; virtual;
  468.      Disposes of the TStatusLine object.
  469.  
  470. procedure Draw; virtual;
  471.      Draws the status line at the bottom of the desktop.
  472.  
  473. function GetPalette: PPalette; virtual;
  474.      Returns a pointer to CStatusLine, but can be overridden to produce a
  475.      different color mapping.
  476.  
  477. procedure HandleEvent(var Event: TEvent); virtual;
  478.      Handles mouse clicks on the status line, and generates the corresponding
  479.      cmXXXX constant when status line items are selected.  
  480.  
  481. function Hint(AHelpCtx: Word): String; virtual;
  482.      Hint translates a help context constant into a string that will be
  483.      displayed by Draw to the right of the keys shown on the status line.. 
  484.      Generally it must be overridden to perform the desired translation for
  485.      your application.  See TStatusLine.Update for an example using the Hint
  486.      context sensitive help facility.
  487.  
  488. constructor Init(var Bounds: TRect; ADefs: PStatusDef);
  489.      Creates a status line object at the location specified by Bounds, and sets
  490.      up the linked list of status line items.  See Chapter 11, "Turbo Vision
  491.      Tutorial" for a discussion on the creation and use of the status line
  492.      objects.
  493.  
  494. constructor Load(var S: TStream);
  495.      Creates and reads a status line object from stream S.
  496.  
  497. procedure Store(var S: TStream);
  498.      Writes the status line object to stream S, including all of the items
  499.      defined for the status line.
  500.  
  501. procedure Update; 
  502.      While an application has only one status line, the contents of that status
  503.      line can change during the program's execution.  In particular, when the
  504.      menu bar is active or a pull down menu is visible, the status line can
  505.      display a brief help message.  The Update procedure is called internally
  506.      by the status line object to determine which items should currently appear
  507.      on the status line.
  508.           To create "hints" that vary according to the currently active
  509.      pulldown selection requires that a new TStatusLine-derived object be
  510.      declared.  The example code shown below is adapted from TVSHELL8 and
  511.      begins with the overridden Hint function.
  512.        PNewStatusLine = ^TNewStatusLine;
  513.        TNewStatusLine = object(TStatusLine)
  514.          function Hint(AHelpCtx: Word): String; virtual;
  515.        end;
  516.           In InitStatusLine, the StatusLine global variable should be created
  517.      from the TNewStatusLine object, like this:
  518.        StatusLine := New(PNewStatusLine, Init(Bounds,
  519.           NewStatusDef(0, $FFFF,
  520.             NewStatusKey('', kbF10, cmMenu,
  521.             NewStatusKey('~Alt-X~ Exit', kbAltX, cmQuit,
  522.             NewStatusKey('~F2~ Copy', kbF2, cmCopy,
  523.             NewStatusKey('~F3~ Close', kbF3, cmClose,
  524.        ...
  525.           InitMenuBar, as part of the menu initialization, must set up
  526.      appropriate help contexts for each item on the menu which will have an
  527.      associated hint.  Then, in the Hint function, the AHelpCtx parameter is
  528.      compared to the help contexts for which a Hint is defined, and the
  529.      appropriate help context string is returned.
  530.  
  531.        procedure TShell.InitMenuBar;
  532.        { Purpose:
  533.          Defines the pulldown menus used in Shell
  534.        }
  535.        var
  536.           Bounds: TRect;
  537.        begin
  538.           TShell.GetExtent(Bounds);
  539.           Bounds.B.Y := Bounds.A.Y + 1;
  540.           MenuBar := New(PMenuBar, Init(Bounds, NewMenu(
  541.             NewSubMenu('~R~un', hcNoContext, NewMenu(
  542.               NewItem('~R~un', '', 0, cmRunProgram, hcRun,
  543.               NewItem('~E~dit', 'Alt-E', kbAltE, cmEdit, hcEdit,
  544.               NewItem('~V~iew', 'Alt-V', kbAltV, cmView, hcView,
  545.               NewItem('~U~se DOS','Alt-D', kbAltS, cmUseDOS,
  546.                  hcNoContext,
  547.               NewItem('E~x~it', 'Alt-X', kbAltX, cmQuit,
  548.                  hcNoContext,
  549.             nil)))))),
  550.             ...
  551.           nil)))
  552.           )));
  553.        end; { TShell.InitMenuBar }
  554.  
  555.      And finally, the Hint function itself is declared to produce a short hint
  556.      text for each item on the pulldown menu, like this:
  557.        function TNewStatusLine.Hint(AHelpCtx: Word): String;
  558.        begin
  559.           if  AHelpCtx = hcRun  then
  560.             Hint:= 'Run an executable program'
  561.           else
  562.           if  AHelpCtx = hcEdit  then
  563.             Hint:='Edit a text file'
  564.           else
  565.           if  AHelpCtx = hcView  then
  566.             Hint := 'View a text file'
  567.           else
  568.             Hint := '';
  569.        end; { TNewStatusLine.Hint }
  570.  
  571.      Now, when you run the TVSHELL program, each time you drop down the run
  572.      menu and move the cursor from item to item, the first 3 items will display
  573.      a context sensitive hint or prompt on the status line.
  574.  
  575.  
  576.  
  577. TStream object
  578. ------------------------------------------------------------ 
  579. Turbo Vision Hierarchy
  580.   TObject
  581.      TStream
  582.        TDosStream
  583.           TBufStream
  584.        TEmsStream
  585.  
  586. Discussion
  587.      TStream is the root of the various stream objects.  For your applications,
  588.      you must use the descendants, TDosStream, TBufStream or TEmsStream.
  589.  
  590. Example
  591.      See Chapter 15, "Streams" in the Borland Pascal Developer's Guide, for
  592.      numerous examples.
  593.  
  594. Fields
  595. ErrorInfo: Integer;
  596.      Whenever an error has occurred (indicated by Status <> StOk), the
  597.      ErrorInfo field contains additional information.  For some values these
  598.      will be additional stXXXX constants, although for DOS-level file errors,
  599.      ErrorInfo will contain the DOS error code.
  600.  
  601. Status: Integer;
  602.      Holds either stOk or the last error code.  See the stXXXX constants for
  603.      possible Status values.
  604.  
  605. Methods
  606. procedure CopyFrom(var S: TStream; Count: Longint);
  607.      This procedure copies Count bytes from stream S to the current stream
  608.      object.
  609.  
  610. procedure Error(Code, Info: Integer); virtual;
  611.      The various stream methods call Error when a problem is encountered. 
  612.      Error, in turn, calls the procedure pointed to by the global variable
  613.      StreamError (if its not nil).  Once an error condition has been raised,
  614.      you must call Reset before performing additional stream reads or writes.
  615.  
  616. procedure Flush; virtual;
  617.      TStream.Flush has no operation, but is overridden in by descendant
  618.      objects, such as TBufStream, in order to write the buffer to disk.
  619.  
  620. function Get: PObject;
  621.      Reads an object from the stream, interpreting the first bytes as the
  622.      ObjType field of a registeration record.  The ObjType is used to
  623.      determined exactly what type of object this is, and then to call that
  624.      object's Load constructor to create a new instance.
  625.  
  626. function GetPos: Longint; virtual;
  627.      GetPos is overridden in all descendants to compute the current byte
  628.      location within the stream.
  629.  
  630. function GetSize: Longint; virtual;
  631.      GetSize is overridden in all descendants to computer the total number of
  632.      bytes in the stream.
  633.  
  634. procedure Put(P: PObject);
  635.      Writes the ObjType field of the registration record to the stream, and
  636.      calls the object's Store method to write the appropriate data fields.
  637.  
  638. procedure Read(var Buf; Count: Word); virtual;
  639.      All descendants of TStream override this procedure to copy Count bytes
  640.      from the stream into Buf, and to move the current stream position to the
  641.      next object position.
  642.  
  643. function ReadStr: PString;
  644.      Reads a string from the stream and returns a pointer to that string.  This
  645.      function is used by TStringCollection.GetItem to read a string from the
  646.      stream.
  647.  
  648. procedure Reset;
  649.      Clears any existing error conditions.
  650.  
  651. procedure Seek(Pos: Longint); virtual;
  652.      All descendants must override Seek such that it positions the stream's
  653.      current position to the byte offset specified by Pos.
  654.  
  655. procedure Truncate; virtual;
  656.      All descendants must override Truncate to delete all data in the stream
  657.      after the current position.
  658.  
  659. procedure Write(var Buf; Count: Word); virtual;
  660.      All descendants must override this procedure to copy Count bytes from Buf
  661.      and write them to the stream.
  662.  
  663. procedure WriteStr(P: PString);
  664.      Outputs string P to the current stream.
  665.  
  666.  
  667.  
  668. TStreamRec type
  669. ------------------------------------------------------------ 
  670. Declaration:  TStreamRec = record
  671.        ObjType: Word;
  672.        VmtLink: Word;
  673.        Load: Pointer;
  674.        Store: Pointer;
  675.        Next: Word;
  676.      end;
  677. Unit:     Objects
  678. Purpose:
  679.      The TStreamRec record type is used in registering objects prior to storing
  680.      to or loading from a TStream.  You register an object for stream I/O by
  681.      initializing the fields of the TStreamRec and then passing the record as a
  682.      parameter to the RegisterType procedure.  Chapter 15, "Streams", contains
  683.      complete details on performing stream I/O, including initializing and
  684.      using this record type.  The record's fields are used as follows:
  685.        ObjType is a unique number from 1,000 to 65,535 that you choose to
  686.        identify your object.
  687.        VmtLink is an internal link to the object's virtual method table. 
  688.        Normally, you set this field equal to Ofs(TypeOf(TSomeObject)^) where
  689.        TSomeObject is any object type.
  690.        Load is a pointer to the object's Load constructor.
  691.        Store is a pointer to the object's Store method.
  692.        Next is a pointer to the next TStreamRec.  You do not need to initialize
  693.        this value.
  694.      When you define your own variables as TStreamRec types, it is recommended
  695.      that you begin each registration record variable name with the letter R as
  696.      an aid to identifying registration records.  Turbo Vision predefines
  697.      registration records for all of its objects, each beginning with an 'R'
  698.      instead of a 'T'.  For example, TCollection's registration record is
  699.      RCollection. 
  700.      See:  Chapter 15, "Streams," RegisterType
  701.  
  702.  
  703.  
  704. TStringCollection object
  705. ------------------------------------------------------------ 
  706. Turbo Vision Hierarchy
  707.   TObject
  708.      TCollection
  709.        TSortedCollection
  710.           TStringCollection
  711.  
  712. Discussion
  713.      TStringCollection is a special version of TSortedCollection that is
  714.      prebuilt to produce sorted collections of strings.  The use of
  715.      TStringCollection is fully explained in Chapter 14, "Collections" in the
  716.      Borland Pascal Developer's Guide.
  717.      See TCollections, TSortedCollection
  718.  
  719. Fields
  720.      None
  721.  
  722. Methods
  723. function Compare(Key1, Key2: Pointer): Integer; virtual;
  724.      Compares Key1^ to Key2^ as strings and returns -1, 0 or 1.
  725.      See TSortedCollection.Compare for details.
  726.  
  727. procedure FreeItem(Item: Pointer); virtual;
  728.      Where Item points to a string object, FreeItem deletes Item from the
  729.      collection.
  730.  
  731. function GetItem(var S: TStream): Pointer; virtual;
  732.      Uses the TStream.ReadStr function to read a string from stream S and
  733.      return a pointer to a PString containing the result.
  734.  
  735. procedure PutItem(var S: TStream; Item: Pointer); virtual;
  736.      Writes Item^ to stream S.
  737.  
  738.  
  739.  
  740. TStrIndex type
  741. ------------------------------------------------------------ 
  742. Declaration:  
  743.  
  744.      TStrIndex = array[0..9999] of TStrIndexRec;
  745.  
  746. Unit:     Objects
  747.  
  748. Purpose:
  749.      This internal type is used by TStringList and TStrListMaker.
  750.  
  751.  
  752.  
  753. TStrIndexRec type
  754. ------------------------------------------------------------ 
  755. Declaration:  
  756.      TStrIndexRec = record
  757.        Key, Count, Offset: Word;
  758.      end;
  759.  
  760. Unit:     Objects
  761.  
  762. Purpose:
  763.      This internal type is used by TStringList and TStrListMaker.
  764.  
  765.  
  766.  
  767. TStringList object
  768. ------------------------------------------------------------ 
  769. Turbo Vision Hierarchy
  770.   TObject
  771.      TStringList
  772.      TStrListMaker
  773.  
  774. Discussion
  775.      TStringList and TStrListMaker are used to create string resource files. 
  776.      TStrListMaker should be used in a separate program to create the string
  777.      resources, and TStringList should be used to access the previously created
  778.      string resources.  Because both objects have the same ObjType value in
  779.      their stream registration record, its very important that these object
  780.      types not appear in the same program, but should be used in separate
  781.      programs.
  782.      See Chapter 16, "Resources," TStrListMaker
  783.  
  784. Fields
  785.      None
  786.  
  787. Methods
  788. destructor Done; virtual;
  789.      Disposes of the string list.
  790.  
  791. constructor Load (var S: TStream);
  792.      Creates and reads the string list index from stream S. 
  793.      See Chapter 16, "Resources."
  794.  
  795. function Get(Key: Word): String;
  796.      Get is the primary function used to access individual strings in the
  797.      string list.  Key is a numeric value, typically a predefined constant,
  798.      used to access particular strings in the resource file.
  799.      See Chapter 16, "Resources."
  800.  
  801.  
  802.  
  803. TStrListMaker object
  804. ------------------------------------------------------------ 
  805. Turbo Vision Hierarchy
  806.  
  807. Discussion
  808.      TStrListMaker creates the string resources to be subsequently access by
  809.      TStringList.
  810.      See Chapter 16, "Resources," TStringList
  811.  
  812. Methods
  813. destructor Done; virtual;
  814.      Disposes of the string list.
  815.  
  816. constructor Init(AStrSize, AIndexSize: Word);
  817.      Init allocates memory for a string buffer having AStrSize bytes and index
  818.      of AIndexSize elements.  All of the strings that you add to the list are
  819.      added into the string buffer, so AStrSize must be large enough to hold all
  820.      the strings.
  821.  
  822. procedure Put(Key: Word; S: String);
  823.      Use Put to add each string into the string list, where Key is the index
  824.      value to assign to the string, and S is the string value.  The
  825.      TStrListMaker appears to have no error checking so make sure that you do
  826.      not add more elements than were specified by AIndexSize and which will fit
  827.      into the string buffer.
  828.  
  829. procedure Store(var S: TStream);
  830.      Writes the string list to stream S.
  831.  
  832.  
  833.  
  834. TSysErrorFunc type
  835. ------------------------------------------------------------ 
  836. Declaration:  
  837.      TSysErrorFunc = function (ErrorCode: Integer; Drive: Byte)
  838.             : Integer;
  839.  
  840. Unit:     Drivers
  841.  
  842. Purpose:
  843.      TSysErrorFunc defines what the system error handler function looks like. 
  844.      See SysErrorFunc and SystemError for details of intercepting system level
  845.      errors.
  846.  
  847.  
  848.  
  849. TTerminal object
  850. ------------------------------------------------------------ 
  851. Turbo Vision Hierarchy
  852.   TObject
  853.      TView
  854.        TScroller
  855.           TTextDevice
  856.             TTerminal
  857.  
  858. Discussion
  859.      TTerminal stores byte values into a large circular queue buffer, and
  860.      provides all the routines to manage and access the queue.  TTerminal is
  861.      normally used for creating terminal program-like scroll buffers that let
  862.      you page back through the data that has come in over a modem.  The scroll
  863.      buffer is automatically displayed in a scrollable view on the screen, with
  864.      attached horizontal and vertical scroll buffers.  ASCII 10 characters in
  865.      the text are used to delineate one line from the next.
  866.  
  867. Commonly Used Features
  868.      Other than Init, to construct and initialize the object, and Done to
  869.      dispose of the object, you'll are likely to use only the CanInsert
  870.      function, for determining if there is room to add more data to the scroll
  871.      buffer without having to throwaway the oldest data.
  872.  
  873. Example
  874.      Borland provides a good example use of TTerminal in their sample program
  875.      TVTXTDMO.PAS, contained in the TVDEMOS subdirectory (example 
  876.      \TP\TVDEMOS\TVTXTDMO.PAS as used in Turbo Pascal 6.0).  The main body of
  877.      that program creates a TTerminal object by instantiating a window
  878.      (TTerminalWindow), which in turn inserts the TTerminal object into itself.
  879.      The simple program then proceeds to read lines of text from a file and
  880.      place them into the TTerminal scroll buffer, using,
  881.           Writeln( T, St );
  882.      This looks pretty peculiar since T is a Text file.  How is the data
  883.      getting written to the scroll buffer?  Earlier in the program, the
  884.      statements,
  885.        AssignDevice (T, PTerminal(Interior));
  886.        Rewrite( T );
  887.      created a link between the TTerminal scrolling buffer and the T text file
  888.      so that subsequent reads or writes to T are redirected to the scroll
  889.      buffer.
  890.  
  891. Fields
  892. BufSize : Word; { Read only }
  893.      Contains the size of the terminal's scroll buffer area, in bytes.  It is
  894.      set by TTerminal.Init.
  895.  
  896. Buffer: PTerminalBuffer; { Read only }
  897.      Points to the start of the buffer memory allocation.  PTerminalBuffer is a
  898.      pointer to an array of up to 64k bytes in size.
  899.  
  900. QueBack : Word; { Read only }
  901.      Together with QueFront, these variables are indexes into the buffer, with
  902.      QueFront indexing the first character currently in the queue, and QueBack
  903.      indexing the location of the last character stored in the scroll buffer.
  904.  
  905. QueFront : Word; { Read only }
  906.      See QueBack.
  907.  
  908. Methods
  909. procedure BufDec ( var Val: Word );
  910.      This is an internal procedure that decrements Val 1, unless Val is at 0,
  911.      in which case this sets Val to BufSize -1.  BufDec, with BufInc, is used
  912.      for moving the QueFront and QueBack indexes.
  913.  
  914. procedure BufInc ( var Val : Word );
  915.      Like BufDec, increments Val by 1.  If Val is at the end of the buffer,
  916.      then resets Val to 0.
  917.  
  918. function CalcWidth : Integer;
  919.      Computes and returns the length of the longest line in the scroll buffer. 
  920.      This is useful for knowing how far it may need to scroll horizontally.
  921.  
  922. function CanInsert ( Amount : Word ): Boolean;
  923.      Use this function to see if there is space remaining in the scroll buffer.
  924.      If adding Amount bytes to the buffer will require that the oldest data be
  925.      deleted to make room, then CanInsert returns False.  If there is enough
  926.      room to avoid a deletion, CanInsert returns True.
  927.  
  928. destructor Done; virtual;
  929.      Cleans up this object instance, throwing away the buffer and calling
  930.      TTextDevice.Done;
  931.  
  932. procedure Draw; virtual;
  933.      Displays the contents of the scroll buffer on the screen.
  934.  
  935. constructor Init ( var Bounds: TRect;
  936.      AHScrollBar, AVScrollBar: PScrollBar; ABufSize : Word );
  937.      Creates and initializes an instance of TTerminal, assigning its location
  938.      as determined by Bounds, and having the horizontal and vertical scroll
  939.      bars passed to it.  The size of the scroll buffer is set to ABufSize,
  940.      which can be up to a maximum of 65,520 bytes.  To determine if
  941.      TTerminal.Init was unable to allocate the buffer, check to see if Buffer
  942.      is non-nil after the call to Init.  A nil value would mean that the
  943.      allocation failed.
  944.  
  945. function NextLine ( Pos : Word ) : Word;
  946.      Where Pos is an index into the scroll buffer, NextLine scans forwards
  947.      (logically, that is, since it may have to wrap around) to find the start
  948.      of the next line, returning that position as its result.
  949.  
  950. function PrevLines ( Pos : Word; Lines : Word ) : Word;
  951.      Where Pos is an index into the scroll buffer, PrevLine scans backwards to
  952.      return the start of the line that is Lines back from the current line.
  953.  
  954. function StrRead ( var S : TextBuf ) : Byte; virtual;
  955.      As implemented, StrRead returns 0 as its result but performs no other
  956.      action.  It needs to be overwritten if you wish to be able to read data
  957.      from the scroll buffer.  If you plan on overwritting this method, you
  958.      definitely should refer to the source code for TTerminal.StrWrite,
  959.      available in the Run Time Library Source package, available separately
  960.      from Borland.
  961.  
  962. function StrWrite ( var S : TextBuf; Count : Byte ); virtual;
  963.      TextBuf is an array of character bytes.  StrWrite adds Count copies of
  964.      TextBuf to the scroll buffer queue.  Embedded ASCII 13 characters are
  965.      ignored; embedded ASCII 10 (line feed) characters are treated as the start
  966.      of a new line and result in the start of a new line within the scroll
  967.      buffer.
  968.  
  969. function QueEmpty : Boolean;
  970.      Returns True if the que is completely empty, False otherwise.
  971.  
  972.  
  973.  
  974. TTerminalBuffer type
  975. ------------------------------------------------------------ 
  976. Declaration:  
  977.      TTerminalBuffer = array[0..65519] of Char;
  978.  
  979. Unit:     TextView
  980.  
  981. Purpose:
  982.      An internal type declaration for use by Turbo Vision or Turbo Vision
  983.      applications.
  984.  
  985.  
  986.  
  987. TTextDevice object
  988. ------------------------------------------------------------ 
  989. Turbo Vision Hierarchy
  990.   TObject
  991.      TView
  992.        TScroller
  993.           TTextDevice
  994.  
  995. Discussion
  996.      TTextDevice is an abstract object type used by descendant objects.  See
  997.      TTerminal.
  998.  
  999. Fields
  1000. Dummy : Word;
  1001.   The purpose of this field is unknown.
  1002.  
  1003. Methods
  1004. function StrRead ( var S : TextBuf ): Byte; virtual;
  1005.      This is an abstract method that must be overridden in order to support
  1006.      reading data from a text device buffer.
  1007.  
  1008. procedure StrWrite ( var S : TextBuf; Count : Byte ); virtual;
  1009.      This is an abstract method  for sending output to the a text device
  1010.      buffer.  It must be overridden to be useful.
  1011.  
  1012.  
  1013.  
  1014. TTitleStr type
  1015. ------------------------------------------------------------ 
  1016. Declaration:  
  1017.      TTitleStr = string[80];
  1018.  
  1019. Unit:     Views
  1020.  
  1021. Purpose:
  1022.      Defines a type used by TWindow for window title strings.
  1023.  
  1024.  
  1025. TVideoBuf type
  1026. ------------------------------------------------------------ 
  1027. Declaration:  
  1028.      TVideoBuf = array[0..3999] of Word;
  1029.  
  1030. Unit:     Views
  1031.  
  1032. Purpose:
  1033.      This defines the internal type used in video buffer declarations in
  1034.      TGroup.  Video buffers are used to store screen images in cache memory
  1035.      (see GetBufMem) for rapid screen update.
  1036.  
  1037.  
  1038.  
  1039. TView object
  1040. ------------------------------------------------------------ 
  1041. Turbo Vision Hierarchy
  1042.   TObject
  1043.      TView
  1044.  
  1045. Discussion
  1046.      TView is the parent of all visible objects in Turbo Vision.  Generally,
  1047.      you will directly instantiate and use one of the descendants: 
  1048.      TBackground, TButton, TCluster, TFrame, TGroup, THistory, TInputLine,
  1049.      TListViewer, TMenuView, TStatusLine, TStatusText, and their respective
  1050.      descendants.  See the descriptions for objects listed above and also see
  1051.      Chapter 11, "Turbo Vision Tutorial" which describes many of these
  1052.      features.
  1053.  
  1054. Commonly Used Features
  1055.      TView provides much of the functionality of all visible objects in Turbo
  1056.      Vision.  As a consequence, TView has the most methods of any Turbo Vision
  1057.      object.  While many of the methods are primarly used internally and to
  1058.      create new descendant-type objects, most applications will encounter at
  1059.      least the following TView methods:
  1060.      GrowMode, DragMode, HelpCtx, State, Options and EventMask.
  1061.      Commonly used methods include BlockCursor, ClearEvent, CommandEnabled,
  1062.      DataSize, DisableCommands, Draw, DrawView, EnableCommands, GetColor,
  1063.      GetCommands, GetHelpCtx, GetPalette, GetState, HideCursor, NormalCursor,
  1064.      Select, SetCommands, SetState, Show, ShowCursor, Valid, WriteLine and
  1065.      WriteStr.
  1066.  
  1067. Fields
  1068. Cursor: TPoint; { Read only }
  1069.      Records the position of the display cursor.
  1070. DragMode: Byte; { Read/Write }
  1071.      The bits in DragMode indicate the view's dragging characterisitcs when
  1072.      dragged with the mouse.  You must directly set a value to DragMode using
  1073.      the dmXXXX constants.
  1074.      See dmXXXX constants for more information on these settings.
  1075.  
  1076. EventMask: Word; { Read/Write }
  1077.      Set EventMask to mask off or on the classes of messages that are accepted
  1078.      for processing by this view.  A value of $FFFF means that the view will
  1079.      accept all messages.  You set EventMask to a combination of the evXXXX
  1080.      constants.
  1081.      See evXXXX constants
  1082.  
  1083. GrowMode: Byte; { Read/Write  }
  1084.      The bit settings in GrowMode indicate how the view will change shape when
  1085.      it is resized.  You must explicitly assign values to GrowMode.
  1086.      See gfXXXX constants for more information on these bit settings.
  1087.  
  1088. HelpCtx: Word; { Read/Write }
  1089.      Holds the view's help context setting.  You must explicitly store a value
  1090.      here unless there is no help, in which case HelpCtx will have a default of
  1091.      hcNoContext.
  1092.  
  1093. Next: PView; { Read only }
  1094.      Next maintains a c ircular list pointing to the next view, in Z-order.
  1095.  
  1096. Options: Word; { Read/Write }
  1097.      Set Options to determine event processing order (ofPreProcess,
  1098.      ofPostProcess) and to set other attributes defined by the ofXXXX
  1099.      constants.
  1100.  
  1101. Origin: TPoint; { Read only }
  1102.      Describes the upper left corner of the view.
  1103.  
  1104. Owner: PGroup; { Read only }
  1105.      Points to the TGroup that owns this view.
  1106.  
  1107. Size: TPoint; { Read only }
  1108.      Contains the size of the view.
  1109.  
  1110. State: Word; { Read only }
  1111.      The State bits retain information about many view options, including the
  1112.      cursor shape, if the cursor is visible or if the view is selected.
  1113.      See sfXXXX constants, TView.SetState, TView.GetState
  1114.  
  1115. Methods
  1116. procedure BlockCursor;
  1117. Override:  Do not override.
  1118.      Changes the cursor to the solid block cursor by setting the sfCursorIns
  1119.      bit in the State field.
  1120.      See TView.NormalCursor
  1121.  
  1122. procedure CalcBounds(var Bounds: TRect; Delta: TPoint); virtual;
  1123.      CalcBounds is used internally to resize and shape this view in the case
  1124.      that the Owner's view was changed in size.
  1125.  
  1126. procedure ChangeBounds(var Bounds: TRect); virtual;
  1127.      This internal procedure repositions the view.
  1128.  
  1129. procedure ClearEvent(var Event: TEvent);
  1130.      In your HandleEvent methods or overridden HandleEvent methods, whenever
  1131.      you have finished processing an event, you must signal that the event is
  1132.      finished by calling ClearEvent, which sets Event.What := evNothing; and
  1133.      Event.InfoPtr := @Self so that other views can determine who it was that
  1134.      process the event.
  1135.  
  1136. function CommandEnabled(Command: Word): Boolean;
  1137.      Use CommandEnabled to check if a specific command is currently enabled or
  1138.      allowed.  Pass the cmXXXX value as the Command parameter and
  1139.      CommandEnabled will return True if the command is available now, or False
  1140.      if the command has been disabled.
  1141.  
  1142. function DataSize: Word; virtual;
  1143.      Used in conjunction with GetData and SetData to copy the views data to and
  1144.      from a data record.
  1145.      See GetData, SetData
  1146.  
  1147. procedure DisableCommands(Commands: TCommandSet);
  1148.      Commands is a set variable containing a set of commands, specified by
  1149.      their cmXXXX constant values, to be disabled.  Calling DisableCommands
  1150.      causes these commands to become greyed out on the menus and status line.
  1151.      See:  TView.DisableCommands
  1152.  
  1153. destructor Done; virtual;
  1154.      Disposes of the view after erasing it from the screen.
  1155.  
  1156. procedure DragView(Event: TEvent; Mode: Byte; var Limits: TRect; MinSize,
  1157. MaxSize: TPoint);
  1158.      DragView handles redrawing the view while it is being dragged across the
  1159.      string.  Limits defines the rectangle in which the view can be dragged,
  1160.      and MinSize and MaxSize set the minimum and maximum sizes to which the
  1161.      view can be resized.
  1162.  
  1163. procedure Draw; virtual;
  1164.      The Draw method is the only method that should write data to the view's
  1165.      screen area.  Any view that you create, including descendants such as
  1166.      TWindow or TApplication, must override the Draw method in order to display
  1167.      their output on the screen.  Generally, your Draw method must keep track
  1168.      of where the screen image is relative to its internal data structure.  For
  1169.      example, if your code implements a text editor, you do not need to draw
  1170.      all 500 lines that are in the current file.  Instead, Draw would update
  1171.      only the lines that are actually visible.  Sometimes you do not need to
  1172.      redraw the entire view because, perhaps, only a portion of the screen was
  1173.      overwritten by another view such as a dialog.  Call GetClipRect to fetch
  1174.      the coordinates of the minimum area that needs updating.  The use of
  1175.      GetClipRect can noticeably improve performance by minimizing the amount of
  1176.      time spent updating the screen.
  1177.      See TView.DrawView, TView.GetClipRect
  1178.  
  1179. procedure DrawView; 
  1180.      DrawView is the preferred method to call when you need to update the view.
  1181.      That's because DrawView makes a check to determine if the view is exposed
  1182.      (not hidden behind another view) before attempting to call Draw.  Draw
  1183.      doesn't care if the view is visible since Turbo Vision will automatically
  1184.      clip away text that doesn't currently appear in a view.
  1185.      See TView.Draw
  1186.  
  1187. procedure EnableCommands(Commands: TCommandSet);
  1188.      Commands is a set variable containing a set of commands, specified by
  1189.      their cmXXXX constant values, to be enabled.  EnableCommands is the
  1190.      inverse of DisableCommands and restores commands to an operable state. 
  1191.  
  1192. procedure EndModal(Command: Word); virtual;
  1193.      Used internally in conjunction with ExecView for displaying modal views,
  1194.      such as dialogs, to terminate the modal view.
  1195.      See TGroup.EndModal, TGroup.Execute, TGroup.ExecView
  1196.  
  1197. function EventAvail: Boolean;
  1198.      Returns True if an event is available.
  1199.  
  1200. function Execute: Word; virtual;
  1201.      Execute is overridden in TGroup descendants to provide the event loop that
  1202.      makes the view a modal view. 
  1203.      See TGroup.EndModal, TGroup.Execute, TGroup.ExecView
  1204.  
  1205. function Exposed: Boolean;
  1206.      If at least some part of the view can be seen on the screen, then Exposed
  1207.      returns True.  If the view is completely hidden, then Exposed returns
  1208.      False.
  1209.  
  1210. procedure GetBounds(var Bounds: TRect);
  1211.      Returns the upper left and lower right corners of this view in Bounds,
  1212.      relative to the owner of the view.
  1213.  
  1214. procedure GetClipRect(var Clip: TRect);
  1215.      Returns the upper left and lower right corners in Clip of the minimum
  1216.      sized area that needs to be redrawn.  Uses this procedure in Draw to help
  1217.      locate only the area on the screen that needs to be updated.
  1218.      See TView.Draw
  1219.  
  1220. function GetColor(Color: Word): Word;
  1221.      Color contains two color indexes, one in the high byte and one in the low
  1222.      byte.  GetColor maps these indexes into the each color palette, in turn,
  1223.      going all the way back to the palette containing the video color
  1224.      attributes.  These values are then returned in the corresponding high and
  1225.      low bytes of the result.
  1226.  
  1227. procedure GetCommands(var Commands: TCommandSet);
  1228.      Use GetCommands to fetch a set containing all of the currently enabled
  1229.      commands.
  1230.  
  1231. procedure GetData(var Rec); virtual;
  1232.      This procedure is overridden in descendants to copy the appropriate amount
  1233.      of view data to Rec.  This procedure is primarily of interest to dialog
  1234.      box controls.
  1235.  
  1236. procedure GetEvent(var Event: TEvent); virtual;
  1237.      Returns the next event from the event queue (typically called after
  1238.      calling TView.EventAvail)
  1239.  
  1240. procedure GetExtent(var Extent: TRect);
  1241.      Similar to GetBounds, except that GetExtent sets Extent.A := (0,0) such
  1242.      that Extent.B, which is set to TView.Size, reflects the total extent of
  1243.      the view relative to the upper left corner.
  1244.  
  1245. function GetHelpCtx: Word; virtual;
  1246.      Returns the TView.HelpCtx value.  
  1247.  
  1248. function GetPalette: PPalette; virtual;
  1249.      The default GetPalette returns nil, so most views will elect to override
  1250.      this function such that it returns a pointer to the color palette for this
  1251.      view.
  1252.      See Chapter 13, "More Turbo Vision Features" for an in depth discussion of
  1253.      color usage in Turbo Vision.
  1254.  
  1255. procedure GetPeerViewPtr(var S: TStream; var P);
  1256.      Used by Load when certain objects need to load a peer view, P,  from
  1257.      stream S, such as a list box needing to load it scroll bar object.
  1258.      See TView.Store, Chapter 15, "Streams" and Chapter 16, "Resources".
  1259.  
  1260. function GetState(AState: Word): Boolean;
  1261.      AState can be set to multiple combinations of the sfXXXX constants and
  1262.      returns True if the the indicated bits are set in the TView.State
  1263.      variable.
  1264.      See TView.State, sfXXXX constants
  1265.  
  1266. procedure GrowTo(X, Y: Integer);
  1267.      Calls TView.Locate to adjust the size of the view.
  1268.  
  1269. procedure HandleEvent(var Event: TEvent); virtual;
  1270.      Every view must override the HandleEvent method.  This is where events are
  1271.      recognized and parceled out to make the view come alive.  For an example,
  1272.      see TVSHELL8.PAS, TShell.HandleEvent, in the Borland Pascal Developer's
  1273.      Guide.
  1274.      See evXXXX constants, cmXXXX constants, Chapter 11, "Turbo Vision
  1275.      Tutorial"
  1276.  
  1277. procedure Hide;
  1278.      Hides the view.  See TView.Show
  1279.  
  1280. procedure HideCursor;
  1281.      Hides the cursor.  See TV iew.ShowCursor
  1282.  
  1283. constructor Init(var Bounds: TRect);
  1284.      Creates an initializes a TView object and places it according to the
  1285.      Bounds parameter.  You may wish to directly assign values other than
  1286.      defaults, to State, Options, EventMask, GrowMode and DragMode.
  1287.  
  1288. procedure KeyEvent(var Event: TEvent);
  1289.      KeyEvent ignores all incoming events until it gets an evKeyDown event, and
  1290.      it returns that event.
  1291.  
  1292. constructor Load(var S: TStream);
  1293.      Creates and reads a view from stream S.
  1294.  
  1295. procedure Locate(var Bounds: TRect);
  1296.      Changes the boundaries of the view and redisplays the view on the screen.
  1297.  
  1298. procedure MakeFirst;
  1299.      Moves this view to the first position (closest to the screen) in the
  1300.      owner's Z-ordered list of views.
  1301.  
  1302. procedure MakeGlobal(Source: TPoint; var Dest: TPoint);
  1303.      Use MakeGlobal (see also MakeLocal) to convert Source, which contains view
  1304.      relative coordinates, to screen coordinates.  The converted value is
  1305.      returned in Dest.
  1306.  
  1307. procedure MakeLocal(Source: TPoint; var Dest: TPoint);
  1308.      Converts the screen coordinates into view relative coordinates.  See
  1309.      MakeGlobal.
  1310.  
  1311. function MouseEvent(var Event: TEvent; Mask: Word): Boolean;
  1312.      Mask is an evMouse event.  MouseEvent sets Event to the next mouse event
  1313.      and returns True if the Event.What field matches Mask, and False if when
  1314.      evMouseUp occurs.  Typically, this function is called when a mouse is
  1315.      being dragged.  To process the dragging operation, keep calling this
  1316.      routine until it returns False, meaning that the mouse button has been let
  1317.      up.
  1318.  
  1319. function MouseInView(Mouse: TPoint) : Boolean;
  1320.      If the point described by Mouse (in screen coordinates) lies within this
  1321.      view, then MouseInView returns True.
  1322.  
  1323. procedure MoveTo(X,Y: Integer);
  1324.      Keeping the view the same size, MoveTo moves the upper left corner, and
  1325.      hence the entire view, to the new point (X,Y).
  1326.  
  1327. function NextView: PView;
  1328.      NextView returns a pointer to the next view, in sequence, in the owner's
  1329.      list of views, or nil if it has reached the end of the list.
  1330.  
  1331. procedure NormalCursor;
  1332.      Sets the screen cursor to an underscore-style cursor.  See
  1333.      TView.BlockCursor.
  1334.  
  1335. function Prev: PView;
  1336.      Prev returns a pointer to the previous view, in sequence, in the owner's
  1337.      list of views, and cycles back to the beginning of the list if it has
  1338.      reached the end.
  1339.  
  1340. function PrevView: PView;
  1341.      Identical to TView.Prev except that if PrevView reaches the beginning of
  1342.      the view list, PrevView returns nil.
  1343.  
  1344. procedure PutEvent(var Event: TEvent); virtual;
  1345.      Using PutEvent, you can force one and only one event to be inserted as the
  1346.      next event in the event queue.  Event will become the next event retrieved
  1347.      by GetEvent.
  1348.  
  1349. procedure PutInFrontOf(Target: PView);
  1350.      Where Target is any view in this view's owner's view list, PutInFrontOf
  1351.      moves this view to be placed directly in front of Target.
  1352.  
  1353. procedure PutPeerViewPtr(var S: TStream; P: PView);
  1354.      The Store method calls this routine to write the "peer" view pointer P to
  1355.      stream S.
  1356.  
  1357. procedure Select;
  1358.      Select makes this view the active view in the group, and if the owning
  1359.      group is on the focused chain, then this view becomes the focused view.
  1360.  
  1361. procedure SetBounds(var Bounds: TRect);
  1362.      This is an internal routine called by ChangeBounds.
  1363.  
  1364. procedure SetCommands(Commands: TCommandSet);
  1365.      Sets the currently list of enabled commands to the set passed in the
  1366.      Commands parameter.  See TView.EnableCommands, TView.DisableCommands
  1367.  
  1368. procedure SetCursor(X, Y: Integer);
  1369.      Moves the screen cursor to (X,Y) where X and Y are local coordinates.
  1370.  
  1371. procedure SetData(var Rec); virtual;
  1372.      Copies TView.DataSize bytes from Rec to the view's data fields.  See
  1373.      TView.Datasize, TView.GetData
  1374.  
  1375. procedure SetState(AState: Word; Enable: Boolean); virtual;
  1376.      Use SetState to either set or clear bits in the TView.State variable.  If
  1377.      Enable is True, then the bits specified by AState are set, and if Enable
  1378.      is False, then the bits specified by AState are cleared.
  1379.  
  1380. procedure Show;
  1381.      Causes the view to be displayed.  See TView.Hide.
  1382.  
  1383. procedure ShowCursor;
  1384.      Makes the screen cursor visible (the default condition is a hidden
  1385.      cursor).
  1386.  
  1387. procedure SizeLimits(var Min, Max: TPoint); virtual;
  1388.      Sets Min to (0,0) and Max to Owner^.Size.
  1389.  
  1390. procedure Store(var S: TStream);
  1391.      Writes this view to stream S.
  1392.  
  1393. function TopView: PView;
  1394.      Returns a pointer to the view modal view that is on top.
  1395.  
  1396. function Valid(Command: Word): Boolean; virtual;
  1397.      Each view contains aValid method which should be overridden to check for
  1398.      specific error conditions appropriate to your views.  When Command equals
  1399.      cmValid, then the view should return False if some problem has occurred
  1400.      when instantiating the view.  Use Valid to check for any type of errors -
  1401.      its up to you to define what those error conditions might be.  An example
  1402.      might be a view that after initialization is unable to find its data file.
  1403.      Valid might call an error handling routine to display the error, and
  1404.      return False.
  1405.           If  Command is not equal to cmValid, then Command equals the returns
  1406.      result from a modal dialog and the view can make specific checks based on
  1407.      this parameter.  An example usage of Valid is given in Chapter 13, "More
  1408.      Turbo Vision Features".
  1409.  
  1410. procedure WriteBuf(X, Y, W, H: Integer; var Buf);
  1411.      WriteBuf is called from with TView.Draw to copy the bytes from Buf to the
  1412.      location on the view specified by the coordinates (X,Y) and extending over
  1413.      W characters and down H lines.  Buf is an array of words, with each word
  1414.      containing both a character to output and its corresponding video memory
  1415.      color attribute (See TDrawBuffer)
  1416.  
  1417. procedure WriteChar(X, Y: Integer; Ch: Char; Color: Byte; Count: Integer);
  1418.      From within a TView.Draw method, WriteChar copies the character Ch, having
  1419.      the color index Color, to the screen, starting at (X,Y) and continuing for
  1420.      Count number of characters.
  1421.  
  1422. procedure WriteLine(X, Y, W, H: Integer; var Buf);
  1423.      From within a TView.Draw method, WriteLine outputs Buf (which is an array
  1424.      of Words; see TDrawBuffer), starting at the view's coordinates (X,Y), and
  1425.      copies W bytes from Buf.  Important!  W should be exactly equal to the
  1426.      number of characters to copy from Buf.  If larger than the contents of the
  1427.      string represented in Buf, then WriteBuf will copy data beyond the end of
  1428.      Buf and random data will appear at those locations.  If  H is more than 1,
  1429.      then WriteLine displays the contents of Buf on each of the succeeding
  1430.      lines.
  1431.  
  1432. procedure WriteStr(X, Y: Integer; Str: String; Color: Byte);
  1433.      WriteStr is probably the most commonly used method for performing output
  1434.      within Draw methods.  Use WriteStr to output the string Str to the screen,
  1435.      starting at (X,Y) and having the color index specified by Color.
  1436.  
  1437.  
  1438.  
  1439. TWindow object
  1440. ------------------------------------------------------------ 
  1441. Turbo Vision Hierarchy
  1442.   TObject
  1443.      TView
  1444.        TGroup
  1445.           TWindow
  1446.  
  1447. Discussion
  1448.      TWindow is one of the core TView-derived objects, used for all types of
  1449.      windows including dialog boxes.  Windows can have optional titles, window
  1450.      numbers, close and zoom icons.  The TWindow object encapsulates and
  1451.      provides all the functionality need to perform window resizing, dragging,
  1452.      closing and includes features for maintaining scroll bars.
  1453.  
  1454. Fields
  1455. Flags: Byte; { Read/Write }
  1456.      Bit positions in the Flags byte are set using the wfXXXX constants to
  1457.      indicate if the window can grow, close, move or zoom.  See wfXXXX
  1458.      constants
  1459.  
  1460. Frame: PFrame; { Read only }
  1461.      Points to the TFrame object linked to this window.
  1462.  
  1463. Number: Integer; { Read/Write }
  1464.      Contains the window's number which if in the range of 1 to 9, appears in
  1465.      the upper right corner of the window and allows the window to be directly
  1466.      selected with the  Alt-n key combination.
  1467.  
  1468. Palette: Integer; { Read/Write }
  1469.      Windows can choose from one of three different palettes, CBlueWindow,
  1470.      CCyanWindow or CGrayWindow depending upon the window's usage.  Palette
  1471.      contains the vlaue of one of the constants wpBlueWindow, wpCyanWindow or
  1472.      wpGrayWindow, with wpBlueWindow as the default value.
  1473.  
  1474. Title: PString; { Read/Write }
  1475.      Points to a string holding the window's title (if any).
  1476.  
  1477. ZoomRect: TRect; { Read only }
  1478.      Specifies the normal window boundaries for the window, as specified by the
  1479.      Bounds passed to the Init constructor.  During program execution, the
  1480.      window can be resized or shrunk; however ZoomRect always holds the
  1481.      original window coordinates so that if you choose the zoom icon, the
  1482.      window can be resized to its original coordinates.
  1483.  
  1484. Methods
  1485. procedure Close; virtual;
  1486.      Equivalent to calling TWindow.Done, and is normally called by the
  1487.      HandleEvent method when cmClose is received.
  1488.  
  1489. destructor Done; virtual;
  1490.      Disposes of the window.
  1491.  
  1492. function GetPalette: PPalette; virtual;
  1493.      Returns a pointer to one of the palettes, CBlueWindow, CCyanWindow or
  1494.      CGrayWindow, depending on the value of TWindow.Palette.
  1495.  
  1496. function GetTitle(MaxSize: Integer): TTitleStr; virtual;
  1497.      This is an overridable function that returns Title^.  However, you can
  1498.      override this function to truncate Title^ if its length exceeds MaxSize
  1499.      characters, or you can have it produce an abbreviated title string.
  1500.  
  1501. procedure HandleEvent(Event: TEvent); virtual;
  1502.      You will probably override this method (before or after calling
  1503.      TWindow.HandleEvent), to handle your application specific event
  1504.      processing.  You can intercept the cmClose and cmZoom commands here, as
  1505.      well has trap keyboard events, as in a word processor.
  1506.  
  1507. constructor Init(var Bounds: TRect; ATitle: TTitleStr; ANumber: Integer);
  1508.      Call Init to create a new window having the size and position specified by
  1509.      Bounds, the title specified by ATitle, and a window number specified by
  1510.      ANumber.  If  ANumber is in the range 1 to 9, then the window can be
  1511.      selected directly from the keyboard by pressing Alt-n.
  1512.  
  1513. procedure InitFrame; virtual;
  1514.      InitFrame is called by TWindow.Init to create the window's TFrame object
  1515.      border.  If you wish to instantiate a custom TFrame object, override
  1516.      InitFrame to create your TFrame-derived object.
  1517.  
  1518. constructor Load(var S: TStream);
  1519.      Creates and reads a window object from stream S.
  1520.  
  1521. procedure SetState(AState: Word; Enable: boolean); virtual;
  1522.      Calls TView.SetState to set the inherited State bits, specified by AState,
  1523.      to True if Enable is True, or cleared if Enable is False. 
  1524.      TWindow.SetStatehandles the window becoming the selected view, and
  1525.      enabling or disabling window-related commands such as cmNext and cmPrev,
  1526.      as needed.
  1527.  
  1528. procedure SizeLimits(var Min, Max: TPoint); virtual;
  1529.      Calls TView.SizeLimits and sets TView.Min := MinWinSize, where MinWinSize
  1530.      is Turbo Vision global variable.
  1531.      See MinWinSize, TView.SizeLimits
  1532.  
  1533. function StandardScrollBar(AOptions: Word): PScrollBar;
  1534.      By calling TWindow.StandardScrollBar, you can create and insert a scroll
  1535.      bar into the window;  StandardScrollBar returns a pointer to the new
  1536.      scroll bar object.  Set AOptions to sbVertical to create a vertical scroll
  1537.      bar that is automatically sized to just fit in the window at the right
  1538.      hand side, or set AOptions to sbHorizontal to create a perfectly sized
  1539.      scroll bar across the bottom of the window.  If you OR sbHandleKeyboard
  1540.      with either sbVertical or sbHorizontal, the scroll bar will be created so
  1541.      that it will also handle up an down arrow keys, page up and down keys and
  1542.      other navigation keys.
  1543.      See sbXXXX constants
  1544.  
  1545. procedure Store(var S: TStream);
  1546.      Writes the TWindow object to stream S.
  1547.  
  1548. procedure Zoom; virtual;
  1549.      Zooms the window back to its ZoomRect specified size.
  1550.  
  1551.  
  1552.  
  1553. TWordArray type
  1554. ------------------------------------------------------------ 
  1555. Declaration:  
  1556.      TWordArray = array[0..16383] of Word;
  1557.  
  1558. Unit:     Objects
  1559.  
  1560. Purpose:
  1561.      Defines an array of words type for use by any application.
  1562.  
  1563.  
  1564.  
  1565. wfXXXX constants
  1566. ------------------------------------------------------------ 
  1567. TWindow flags
  1568.  
  1569. Constant  Value  Usage
  1570. wfMove    $01 
  1571.                     When bit is set, the window can be moved.
  1572.  
  1573. wfGrow    $02 
  1574.                     When the bit is set, the window can be resized and has a
  1575.                     "grow" icon in the lower right corner.  If you clear this
  1576.                     bit you can prevent a window from being resized.
  1577.  
  1578. wfClose     $04  
  1579.                     Set this bit to add a close icon in the upper left corner
  1580.                     of a window.  Clear the bit to eliminate the icon.
  1581.  
  1582. wfZoom    $08 
  1583.                     When this bit is set, the window contains a zoom icon for
  1584.                     zooming a window to full size.
  1585.  
  1586. See: TWindow, TWindog.Flags
  1587.  
  1588.  
  1589.  
  1590. wnNoNumber constant
  1591. ------------------------------------------------------------ 
  1592. Declaration:  
  1593.      WnNoNumber = 0;
  1594.  
  1595. Unit:     Views
  1596.  
  1597. Purpose:
  1598.      When ever a TWindow.Number field contains this value, it means that the
  1599.      window has no number.  Windows that have no number do not display any
  1600.      number in the upper right corner, nor can they be selected with the
  1601.      Alt-number quick key selection for switching between windows numbered 1
  1602.      through 9.
  1603.  
  1604.  
  1605. WordRec type
  1606. ------------------------------------------------------------ 
  1607. Declaration:  
  1608.      WordRec = record
  1609.        Lo, Hi : Byte;
  1610.      end;
  1611.  
  1612. Unit:     Objects
  1613.  
  1614. Purpose:
  1615.      You can use this type declaration to recast a word value so that you can
  1616.      access the low and high bytes.
  1617.  
  1618.  
  1619.  
  1620. wpXXXX constants
  1621. ------------------------------------------------------------
  1622. Window Palette selection contstants
  1623.  
  1624. TWindows have 3 separate color palettes, as shown in the table below. 
  1625. CBlueWindow (indicated by wpBlueWindow) is normally used for text windows,
  1626. CCyanWindow (indicated by wpCyanWindow) is normally used for messages, and
  1627. CGrayWindow (indicated by wpGrayWindow) is normally used for dialog boxes.  The
  1628. wpXXXX constant, indicating the window color scheme, is stored in
  1629. TWindow.Palette.  You can alter a window's default color scheme, by assigning
  1630. one of the wpXXXX constants to TWindow.Palette, typically after calling the
  1631. window's Init constructor.  Example, where DirWindow is TWindow-derived object
  1632. pointer:
  1633.  
  1634.      DirWindow^.Palette := wpCyanWindow;
  1635.  
  1636.  
  1637. Constant       Value  Usage
  1638. wpBlueWindow   0      Yellow on blue color scheme
  1639. wpCyanWindow   1      Blue on cyan color scheme
  1640. wpGrayWindow   2      Black on gray color scheme
  1641.  
  1642.